Parse-O-Matic: Config

<h1>Parse-O-Matic: Config</h1>

<hl>Note: This is an appendix to the "Parse-O-Matic Scripts" user manual.</hl>

<h2>Table of Contents</h2>

You can click on any section title below to jump directly to that section.

   <a href="#INTRODUC">Introduction</a>
   <a href="#CONFIGSE">The Config Section</a>
      <a href="#SAMPLESC">Sample Script</a>
      <a href="#EXECUTIO">Execution of the Config Section</a>
      <a href="#CMDSAVAI">Commands Available in Config</a>
   <a href="#DOLLCFGV">The $Cfg Variables</a>
      <a href="#OPTIONAL">Optional Input Boxes</a>
      <a href="#FILENAME">File Names</a>
      <a href="#FILEFMTS">File Formats</a>
         <a href="#INPFILFM">Input File Format</a>
            <a href="#TXTFILES">Text Files</a>
            <a href="#DELIMFIL">Delimited Files</a>
            <a href="#BINARYFI">Binary Files</a>
         <a href="#OUTFILFM">Output File Format</a>
      <a href="#DOCUMENT">Documentation</a>

<a name="INTRODUC"><h1>Introduction</h1>

The Config (short for "Configuration") section lets your script adjust how the underlying Parse-O-Matic application looks and behaves. You can, for example, alter the captions and hints on the optional input boxes.

The techniques described here are not always available; some Parse-O-Matic applications have limitations on how much they can be configured.

<a name="CONFIGSE"><h1>The Config Section</h1>

<a name="SAMPLESC"><h2>Sample Script</h2>

By convention, the Config section appears at the beginning of your script. Here is a sample script:
<hl>
  Config
    $CfgEnableOptionX = 'N'
    $CfgEnableOptionY = 'N'
    $CfgEnableOptionZ = 'Y'
    $CfgCaptionZ      = '&CustNum'
    $CfgHintZ         = 'Enter the 5-digit customer number here'
  End
  If $OutData[1 5] <> $OptionZ Done
  OutEnd $OutData
</hl>
For the standard Parse-O-Matic user interface, this would disable the first two optional input boxes, leaving only the third one (known generically as OptionZ). It would be given the caption "CustNum", with a hotkey of Alt-C (as indicated by the ampersand preceding the C in '&CustNum').

<a name="EXECUTIO"><h2>Execution of the Config Section</h2>

The Config section is run when a script is loaded, or (for most script-enabled Parse-O-Matic applications) when you press F5, or if the application notices that the script has been changed.

The Config section is run again when the script is run, just before the <a href="pommel://Help-FlowControl.txt|Flow Control">TaskInit</a> step.

Whenever the Config section is run, the rest of the script is also checked for syntax errors.

<a name="CMDSAVAI"><h2>Commands Available in Config</h2>

Since the Config section deals with overall processing parameters, you should not use it to initialize variables Ч that should be done in the <a href="pommel://Help-FlowControl.txt|Flow Control">TaskInit</a> step.

In most cases, you will simply assign values to <a href="#DOLLCFGV">$Cfg</a> variables. In addition to this, though, you can use the following commands:
<hl>
  Begin, End, If, Otherwise, Stop, NextStep
</hl>
These let your Config section make certain decisions based on other factors (for example: whether or not $TestMode = 'Y'). You cannot read input (because there is none within the Config section), nor can you generate output.

<a name="DOLLCFGV"><h1>The $Cfg Variables</h1>

The settings you make in the Config section are performed by assigning a value to one of the special variables starting with the characters <hl>$Cfg</hl>. These are described below.

<a name="OPTIONAL"><h2>Optional Input Boxes</h2>

The standard Parse-O-Matic interface has three combo boxes known generically as OptionX, OptionY and OptionZ. Your particular Parse-O-Matic application may give them different names, but in all cases they are used for supplying additional information to the application or a script.

You can alter the characteristics of these input boxes with the following $Cfg variables:

<hl>$CfgCaptionX</hl>,<hl> $CfgCaptionY</hl> and <hl>$CfgCaptionZ</hl> set the caption. You can include an ampersand in the value to define a hotkey. For example:
<hl>
  $CfgCaptionY = '<b>&</b>PhoneNum'
</hl>
This will alter the caption for the OptionY input box to "PhoneNum", with a hotkey of Alt-P. You should test your script to ensure that the hotkey is not already used by another control, and that the caption fits in the space provided.

<hl>$CfgEnableOptionX</hl>,<hl> $CfgEnableOptionY</hl> and <hl>$CfgEnableOptionZ</hl> turn on or off the optional input boxes. If an input box is turned off, it will be "greyed-out" and will contain the string "(Not used by this application)". For example:
<hl>
  $CfgEnableOptionX = 'N'
  $CfgEnableOptionY = 'Y'
  $CfgEnableOptionZ = 'N'
</hl>
This would turn off all optional input boxes except OptionY.

<hl>$CfgHintX</hl>,<hl> $CfgHintY</hl> and <hl>$CfgHintZ</hl> provide a "hover hint". This is a short phrase that appears when the user pauses over the input box with the mouse cursor.

<a name="FILENAME"><h2>File Names</h2>

The standard Parse-O-Matic interface has an input box for the Input File name and one for the Output File name. Both of these have default values, which are set by the following variables:
<hl>
  $CfgDefaultIFN   Default input file name
  $CfgDefaultOFN   Default output file name
</hl>
For example, in the <a href="http://members.aol.com/getmydata/pc-sample.htm">TextHarvest</a> application, if you clear (i.e. leave empty) the Input File input box and then exit it (e.g. by pressing Tab), the program fills in the input file name <hl>ThingsToDo.txt</hl> Ч one of the sample files included in the TextHarvest package.

You can change these defaults with $CfgDefaultIFN and $CfgDefaultOFN.

Note, however, that when a script is loaded these default names do not automatically override the file names already in the input boxes. These $Cfg variables simply provide the end user with a quick way to enter the file name. If the default file name is quite long (for example, if it is located in a sub-sub-sub-directory), this can save the end user a lot of typing.

Two special file names are recognized by Parse-O-Matic: <hl>Clipboard</hl> and <hl>None</hl>. 'Clipboard' takes input from (or sends output to) the Windows text clipboard. 'None' means precisely what its name implies:  if you take input from 'None', you'll get no data (except the word "None"); if you send output to 'None', it disappears.

<a name="FILEFMTS"><h2>File Formats</h2>

The format of the input and output files can be altered from the default setting (plain text) with the following $Cfg variables:
<hl>
  $CfgInpFileType   Input file format (examples: 'Text', 'Binary', 'Delimited')
  $CfgOutFileType   Output file format
  $CfgRecLen        Record length for Binary files
  $CfgDelimiter     Record-ending delimiter character for Delimited files
</hl>
These settings are described below.

<a name="INPFILFM"><h3>Input File Format</h3>

If you do not specify a setting for $CfgInpFileType, it is generally assumed to be 'Text' (unless the underlying Parse-O-Matic application has a different default).

The Text type can read standard Windows-style text files (i.e. each line ends with the carriage return and linefeed characters: decimal #13#10; hex $0D$0A) or Unix-style text files (where each line ends with the linefeed character).

Here are the supported values for $CfgInputFileType:
<hl>
  'Text'        Windows-style or Unix-style text files
  'TextLF'      Unix-style text files only
  'TextCR'      Macintosh-style text files
  'Delimited'   Records terminated with a specific character
  'Binary'      Fixed-record-length file or Manual Read Mode
</hl>
The Delimited and Binary file types are described below.

<a name="TXTFILES"><h4>Text Files</h4>

The three text file formats (Text, TextLF and TextCR) try to deal gracefully with a certain amount of variation. For example, TextCR will ignore any linefeed characters, while TextLF will ignore any carriage return characters. If for some reason you wish to retain these characters, you can use the Delimited file format (described below).

<a name="DELIMFIL"><h4>Delimited Files</h4>

If you set $CfgInpFileType to 'Delimited', you must also specify the delimiter   character that ends each record (with the possible exception of the last one). For example, you could process Macintosh-style text files by using the following technique instead of the TextCR format:
<hl>
  Config
    $CfgInpFileType = 'Delimited'
    $CfgDelimiter   = $0D
  End
</hl>
This will read records that end with a carriage return character. The delimiter character is not included in the result.

Multi-character delimiters are not supported, but in most cases you can simply parse out the excess characters. For example, if you read a standard Windows-style text file as a Delimited type, looking only for the linefeed ($0A), each record would have a spurious carriage return ($0D) at the end which is easily removed with the TrimChar command.

<a name="BINARYFI"><h4>Binary Files</h4>

If you set $CfgInpFileType to 'Binary', you must also specify a record length via the $CfgRecLen variable.

A value of 0 (zero) means "Manual Read Mode": your script will handle all reading with commands such as Bookmark, ReadFor, ReadNext, ReadUntil and so on.

Note:  Manual Read Mode is not supported by all Parse-O-Matic applications.
       In general, if the application does some preprocessing of the data,
       Manual Read Mode is not available. This prevents the script from
       interfering with the underlying application.

A positive integer value means that you are reading records of fixed length. In a fixed-record-length file, all records (with the possible exception of the last one) are exactly as many bytes as you specify in $CfgRecLen. For example:
<hl>
  Config
    $CfgInpFileType = 'Binary'
    $CfgRecLen      = 80
  End
</hl>
This will read records that are 80 characters long. In principle you can read records that are several billion characters long, though in practice this might create memory issues.

<a name="OUTFILFM"><h3>Output File Format</h3>

Since scripts can control output precisely (using the Output command), your output file can adopt any format you wish. Thus, the $CfgOutFileType variable is used for documentation purposes only. For example, it is displayed when you view a Help file for a script.

For the sake of consistency the value of $CfgOutFileType is checked against a list of permissible file types (Text, TextLF, Delimited and Binary). If you are outputting a proprietary format (such as might be natively supported by a database or spreadsheet), it is best to set $CfgOutFileType to 'Binary'.

<a name="DOCUMENT"><h2>Documentation</h2>

When you create a script, it is a good idea to also create a Help file to go with it. Script-enabled Parse-O-Matic applications recognize that a Help file is present when a file exists with the same name as the script, but with the string "<hl>Help-</hl>" in front of the name. Thus, if you created a script named:
<hl>
  ScrFixData.txt
</hl>
then the corresponding Help file would be named:
<hl>
  Help-ScrFixData.txt
</hl>
(By convention, script filenames start with <hl>Scr</hl> and have a <hl>.txt</hl> extension.)

Once you've prepared the Help file, you can then set the following values in your script's Config section:
<hl>
  ЧЧЧЧЧЧЧЧЧЧЧЧЧЧ   ЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧ
  Variable Name    Explanation
  ЧЧЧЧЧЧЧЧЧЧЧЧЧЧ   ЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧ
  $CfgCopyright    Copyright notice (e.g. 'Copyright (C) 2005 by WhizzCo')
  $CfgVersion      The version of the script (e.g. '1.00.00');
  $CfgProgrammer   The name of the primary programmer of the script
  $CfgEmail        Email address to contact the people who wrote the script
  $CfgLicense      Terms of use Ч you can append several strings with the
                   continuation convention (the >> characters) to create a
                   multi-line explanation.
  ЧЧЧЧЧЧЧЧЧЧЧЧЧЧ   ЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧЧ
</hl>
When the Help file is displayed by the application, these items will also be displayed (provided you assigned them a value).

If you are using Pommel markup for your Help file, you can insert a link to jump to this information by using an anchor tag HRef of <hl>#AUTABOUT</hl> (which stands for "Automatic About"). For more about Pommel markup (which is similar to HTML), see the PommelScan user manual, which is included with many Parse-O-Matic applications.